---
target: Umo Office Viewer
keywords: Umo Office Viewer,office在线预览,wps在线预览,docx在线预览,word在线预览,pdf在线预览
description: Umo Office Viewer 是一款 Office 文档查看器，支持在 Web 页面中查看 40 余种主流的办公文档。
---

# 配置选项

用于配置 Umo Office Viewer 插件的显示和行为。Umo Office Viewer 需要和 [Umo Office Convert](../office-convert) 一起搭配完成文档预览。

## 默认配置

```javascript
{
  lang: 'zh-CN',
  theme: 'light',
  title: undefined,
  meta: [],
  showHeader: true,
  showMenu: true,
  showAside: false,
  downloadable: true,
  exportable: true,
  printable: true,
  closeable: false,
  serverUrl: undefined,
  fileId: undefined,
  fileUrl: undefined,
  shareUrl: undefined,
  multiPage: false,
  fitWidth: false,
  watermark: {
    text: '',
    columns: 4,
    rows: 4,
    color: 'rgba(0, 0, 0, 0.2)',
    rotation: 30,
    fontSize: 12 * window.devicePixelRatio
  },
  needPassword: false,
  onClose: undefined,
  onValidatePassword: undefined
}
```

## 配置项说明

### lang

**说明**：显示语言，可通过 `setLocale` 方法动态切换。

**类型**：`String`

**默认值**：`'zh-CN'`

**可选值**：`'zh-CN'`、`'en-US'`

### theme

**说明**：主题模式，`auto` 将根据系统深浅色自动切换。

**类型**：`String`

**默认值**：`'light'`

**可选值**：`'light'`、`'dark'`、`'auto'`

### title

**说明**：文档标题，必须包含文件后缀名（如 `.docx`、`.xlsx`、`.pptx` 等）。在标题栏显示，同时用于下载、导出的文件名。

**类型**：`String`

**默认值**：`''`

**是否必填**：是

### meta

**说明**：文档元信息，在侧边栏信息面板展示。

**类型**：`Array<{ label: String; content: any }>`

**默认值**：`[]`

### showHeader

**说明**：是否显示标题栏，您可以使用此配置项隐藏标题栏。

**类型**：`Boolean`

**默认值**：`true`

**可选值**：`true`、`false`

### showMenu

**说明**：是否显示标题栏菜单（信息、下载、导出、打印、分享等），您可以使用此配置项功能菜单。

**类型**：`Boolean`

**默认值**：`true`

**可选值**：`true`、`false`

### showAside

**说明**：默认是否显示侧边栏（信息、缩略图），可用 `openAside('info'|'thumbs')` 方法动态打开，用户也可手动打开。

**类型**：`Boolean`

**默认值**：`false`

**可选值**：`true`、`false`

### downloadable

**说明**：是否允许下载原始文档。

**类型**：`Boolean`

**默认值**：`true`

**可选值**：`true`、`false`

### exportable

**说明**：是否允许用户将预览文档导出为 PDF 文档。

**类型**：`Boolean`

**默认值**：`true`

**可选值**：`true`、`false`

### printable

**说明**：是否允许用户打印文档。

**类型**：`Boolean`

**默认值**：`true`

**可选值**：`true`、`false`

### closeable

**说明**：是否显示关闭按钮，点击将触发 `onClose` 回调与 `closed` 事件，如果在弹框中预览文档，可利用这一选项进行关闭弹框等。

**类型**：`Boolean`

**默认值**：`false`

**可选值**：`true`、`false`

### serverUrl

**说明**：[Umo Office Convert](../office-convert)服务的 URL 地址，例如: `http://127.0.0.1:1236`。

**类型**：`String`

**默认值**：`undefined`

**是否必填**：`是`

### fileId

**说明**：文件 ID，即任务 ID，配置该项可直接从[Umo Office Convert](../office-convert)服务中获取已转换完成的文件，而不经过转换服务，极大提高加载速度，减少服务器资源消耗。

**类型**：`String`

**默认值**：`undefined`

**是否必填**：`fileId` 和 `fileUrl` 至少配置一项

### fileUrl

**说明**：要预览的文件地址 URL。

**类型**：`String`

**默认值**：`undefined`

**是否必填**：`fileId` 和 `fileUrl` 至少配置一项

### shareUrl

**说明**：分享链接，配置后菜单中显示"分享"入口，用户可将配置的链接分享给其他用户或者嵌入到其他页面。

**类型**：`String`

**默认值**：`undefined`

### multiPage

**说明**：默认是否开启多页模式，`false` 为横向单列，`true` 为横向多列。

**类型**：`Boolean`

**默认值**：`false`

**可选值**：`true`、`false`

### fitWidth

**说明**：页面大小是否自适应容器宽度（内部计算缩放）。

**类型**：`Boolean`

**默认值**：`false`

**可选值**：`true`、`false`

### watermark

**说明**：水印设置，您也可以通过 `setWatermark` 方法来动态设置或修改页面水印。更多说明见：[水印与密码](./security)。

**类型**：`Object`

**配置项**：

- `text`：`String`，水印内容，建议不超过 30 个字符。
- `columns`：`Number`，水印列数，默认值为 `4`。
- `rows`：`Number`，水印行数，默认值为 `4`。
- `color`：`String`，字体颜色，默认值为 `'rgba(0, 0, 0, 0.2)'`，可选值为合法的 CSS 颜色值。
- `rotation`：`Number`，旋转角度，默认值为 `30`。
- `fontSize`：`Number`，字体大小，默认值为 `12 * window.devicePixelRatio`，单位为 px。

### needPassword

**说明**：是否需要密码才能预览。更多说明见：[水印与密码](./security)。

**类型**：`Boolean`

**默认值**：`false`

**可选值**：`true`、`false`

### onClose

**说明**：关闭按钮点击时调用的回调函数，在配置了 `closeable` 为 `true` 时，必须配置此选项。

**类型**：`Function`

**默认值**：`undefined`

### onValidatePassword

**说明**：密码校验逻辑回调函数，在配置了 `needPassword` 为 `true` 时，必须配置此选项。更多说明见：[水印与密码](./security)。

**类型**：`Function`

**默认值**：`undefined`
